Documentation-only. No parser change; uv run pytest and the -b doctest build both pass.

What was wrong

usage.rst said the period-abbreviation inference applies to "a leading word", and that "the rule only applies to the leading run". Neither holds for any comma form. _peel_leading_titles runs at the head of the part that carries the given name — NO_COMMA segment 0, SUFFIX_COMMA segment 0, and FAMILY_COMMA segment 1 — so:

parse("Morse, Det. Insp. Jane").title   # 'Det. Insp.'
parse("Smith, Xyz.").title              # 'Xyz.'

This is long-standing, not a 2.x regression — 1.4.0 from PyPI behaves identically. Only the description was wrong. customize.rst repeated the same claim and is corrected to match.

New examples

Major. was the example throughout, and it is not an abbreviation — it is a whole word carrying a stray period, so it never illustrated why a period should mean anything. Foo. Xyz. illustrated less still.

The examples now use Det. Insp. Jane Morse. Detective Inspector is a real rank, both parts are real abbreviations, and neither det nor insp is in the shipped vocabulary — so the example actually exercises the structural inference. A line saying so was added, since previously there was no way for a reader to tell which examples depended on vocabulary and which did not.

Framing

The section now opens with what the period means — a trailing period marks an abbreviation, and the parts of a name that get abbreviated are the ones standing outside it, titles and post-nominals — before stating the rule. That is the background-before-behavior shape the other domain-heavy sections use, and it makes the closing limitation legible: only the title direction is inferred.

That closing paragraph is deliberately prose with no doctest. Whether an unrecognized trailing abbreviation should reach suffix is an open design question (issue to follow), and pinning today's answer in an example would prejudge it.

Also

• AGENTS.md's gotcha still named is_leading_title(), a v1 function deleted at the M11 swap, and repeated the same wrong scope claim. It now records the per-segment scoping, all three call sites, that this is the mechanism behind Should parse("Smith, Jr.") put "Jr." in title rather than suffix? #296, and that the three trailing-period rules in the codebase resolve differently from one another.
• A Documentation bullet in the 2.1.0 release log.

🤖 Generated with Claude Code